Distribucija Python paketa: Objavljivanje na PyPI-ju i upravljanje verzijama

Opsežni ekosustav Pythona pokreće ogromna zbirka paketa, lako dostupnih putem Python Package Indexa (PyPI). Ovaj vodič pruža sveobuhvatan pregled kako distribuirati vlastite Python pakete putem PyPI-ja, osiguravajući da budu dostupni programerima diljem svijeta. Istražit ćemo osnovne alate, najbolje prakse za upravljanje verzijama i tijekove rada za stvaranje i objavljivanje visokokvalitetnih Python paketa.

Zašto distribuirati svoj Python paket?

Distribucija vašeg Python paketa nudi brojne prednosti:

• Dijeljenje vašeg rada: Omogućuje drugim programerima da lako ponovno koriste vaš kod, potičući suradnju i inovacije. Zamislite globalni tim koji koristi vaše specijalizirane alate za analizu podataka izgrađene u Pythonu.
• Upravljanje ovisnostima: Pojednostavljuje proces upravljanja ovisnostima u drugim projektima. Vaš paket može se instalirati jednom naredbom, zajedno sa svim svojim ovisnostima.
• Doprinos otvorenom kodu: Omogućuje vam da doprinesete zajednici otvorenog koda i steknete priznanje za svoj rad. Mnoge ključne softverske komponente su paketi otvorenog koda koje održavaju programeri diljem svijeta.
• Kontrola verzija i ažuriranja: Pruža strukturiran način za upravljanje verzijama, izdavanje ažuriranja i rješavanje grešaka. To osigurava da korisnici uvijek imaju pristup najnovijoj i najpouzdanijoj verziji vašeg paketa.
• Jednostavna instalacija: Pojednostavljuje instalaciju za korisnike putem pip install ime-vaseg-paketa.

Osnovni alati za distribuciju Python paketa

Nekoliko alata je ključno za stvaranje i distribuciju Python paketa:

• setuptools: Široko korištena biblioteka za definiranje metapodataka paketa, uključujući naziv, verziju, ovisnosti i ulazne točke. To je de facto standard za pakiranje Python projekata.
• wheel: Format distribucije koji pruža učinkovitiji i pouzdaniji proces instalacije u usporedbi s izvornim distribucijama. Wheelovi su unaprijed izgrađene distribucije koje se mogu instalirati bez potrebe za kompajliranjem.
• twine: Alat za sigurno postavljanje vašeg paketa na PyPI. Twine kriptira vaše vjerodajnice i podatke paketa tijekom prijenosa, štiteći od prisluškivanja i "man-in-the-middle" napada.
• venv/virtualenv: Ovo su alati za stvaranje izoliranih Python okruženja. Korištenje virtualnih okruženja ključno je za upravljanje ovisnostima i izbjegavanje sukoba između različitih projekata.

Postavljanje vašeg projekta

Prije nego što možete distribuirati svoj paket, morate ispravno strukturirati svoj projekt.

Primjer strukture projekta

moj_paket/
├── moj_paket/
│   ├── __init__.py
│   ├── modul1.py
│   └── modul2.py
├── tests/
│   ├── __init__.py
│   ├── test_modul1.py
│   └── test_modul2.py
├── README.md
├── LICENSE
├── setup.py
└── .gitignore

Objašnjenje:

• moj_paket/: Glavni direktorij koji sadrži izvorni kod vašeg paketa.
• moj_paket/__init__.py: Čini direktorij moj_paket Python paketom. Može biti prazan ili sadržavati inicijalizacijski kod.
• moj_paket/modul1.py, moj_paket/modul2.py: Vaši Python moduli koji sadrže stvarni kod.
• tests/: Direktorij koji sadrži vaše jedinične testove. Ključno je napisati testove kako bi se osigurala kvaliteta i pouzdanost vašeg paketa.
• README.md: Markdown datoteka koja pruža opis vašeg paketa, upute za korištenje i druge relevantne informacije. Ovo je često prva stvar koju korisnici vide na PyPI-ju.
• LICENSE: Datoteka koja sadrži licencu pod kojom se vaš paket distribuira (npr. MIT, Apache 2.0, GPL). Odabir odgovarajuće licence ključan je za specificiranje kako drugi mogu koristiti vaš kod.
• setup.py: Glavna konfiguracijska datoteka koja definira metapodatke vašeg paketa i upute za izgradnju.
• .gitignore: Specificira datoteke i direktorije koje Git treba ignorirati (npr. privremene datoteke, artefakti izgradnje).

Stvaranje `setup.py` datoteke

setup.py datoteka je srce distribucije vašeg paketa. Sadrži metapodatke o vašem paketu i upute za njegovu izgradnju i instalaciju. Evo primjera:

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="moj_paket",  # Zamijenite s nazivom vašeg paketa
    version="0.1.0",
    author="Vaše Ime",  # Zamijenite sa svojim imenom
    author_email="vas.email@example.com", # Zamijenite sa svojim emailom
    description="Mali primjer paketa",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/vasekorisnickoime/moj_paket", # Zamijenite s URL-om vašeg repozitorija
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
    install_requires=[
        "requests", # Primjer ovisnosti
    ],
)

Objašnjenje:

• name: Naziv vašeg paketa, koji će se koristiti na PyPI-ju. Odaberite jedinstven i deskriptivan naziv.
• version: Broj verzije vašeg paketa. Slijedite semantičko verzioniranje (pogledajte ispod).
• author, author_email: Vaše ime i email adresa.
• description: Kratak opis vašeg paketa.
• long_description: Duži, detaljniji opis, obično pročitan iz vaše `README.md` datoteke.
• long_description_content_type: Određuje format vašeg dugog opisa (npr. "text/markdown").
• url: URL početne stranice vašeg paketa (npr. GitHub repozitorij).
• packages: Popis paketa koje treba uključiti u vašu distribuciju. `setuptools.find_packages()` automatski pronalazi sve pakete u vašem projektu.
• classifiers: Metapodaci koji pomažu korisnicima da pronađu vaš paket na PyPI-ju. Odaberite odgovarajuće klasifikatore s popisa Trove klasifikatora. Razmislite o uključivanju klasifikatora za podržane verzije Pythona, operativne sustave i licence.
• python_requires: Određuje minimalnu verziju Pythona potrebnu za korištenje vašeg paketa.
• install_requires: Popis ovisnosti koje vaš paket zahtijeva. Te će se ovisnosti automatski instalirati kada se instalira vaš paket.

Upravljanje verzijama: Semantičko verzioniranje

Semantičko verzioniranje (SemVer) je široko prihvaćena shema verzioniranja koja pruža jasan i dosljedan način komuniciranja prirode promjena u vašem paketu.

SemVer broj verzije sastoji se od tri dijela: GLAVNA.MANJA.ZAKRPA.

• GLAVNA (MAJOR): Povećava se kada napravite nekompatibilne promjene API-ja. To ukazuje na značajnu promjenu koja može zahtijevati od korisnika da ažuriraju svoj kod.
• MANJA (MINOR): Povećava se kada dodate funkcionalnost na način koji je kompatibilan s prethodnim verzijama. To označava nove značajke ili poboljšanja koja ne narušavaju postojeći kod.
• ZAKRPA (PATCH): Povećava se kada napravite ispravke grešaka koje su kompatibilne s prethodnim verzijama. Ovo je za male popravke koji ne dodaju nove značajke niti narušavaju postojeću funkcionalnost.

Primjeri:

• 1.0.0: Početno izdanje.
• 1.1.0: Dodana je nova značajka bez narušavanja postojećeg koda.
• 1.0.1: Ispravljena je greška u izdanju 1.0.0.
• 2.0.0: Napravljene su nekompatibilne promjene API-ja.

Korištenje SemVer-a pomaže korisnicima da razumiju utjecaj nadogradnje na novu verziju vašeg paketa.

Izgradnja vašeg paketa

Nakon što konfigurirate svoju `setup.py` datoteku, možete izgraditi svoj paket.

1. Stvorite virtualno okruženje: Preporučuje se stvaranje virtualnog okruženja kako biste izolirali ovisnosti vašeg paketa. Koristite `python3 -m venv .venv` (ili `virtualenv .venv`), a zatim ga aktivirajte (`source .venv/bin/activate` na Linuxu/macOS-u, `.venv\Scripts\activate` na Windowsima).
2. Instalirajte ovisnosti za izgradnju: Pokrenite `pip install --upgrade setuptools wheel`.
3. Izgradite paket: Pokrenite `python setup.py sdist bdist_wheel`. Ova naredba stvara dvije distribucijske datoteke u direktoriju `dist`: izvornu distribuciju (sdist) i wheel distribuciju (bdist_wheel).

`sdist` sadrži vaš izvorni kod i `setup.py` datoteku. `bdist_wheel` je unaprijed izgrađena distribucija koja se može brže instalirati.

Objavljivanje vašeg paketa na PyPI

Prije nego što možete objaviti svoj paket, morate stvoriti račun na PyPI-ju (https://pypi.org/) i stvoriti API token. Taj će se token koristiti za provjeru autentičnosti vaših prijenosa.

1. Registrirajte se na PyPI: Idite na https://pypi.org/account/register/ i stvorite račun.
2. Stvorite API token: Idite na https://pypi.org/manage/account/, pomaknite se do odjeljka "API tokens" i stvorite novi token. Sigurno pohranite ovaj token jer će vam trebati za prijenos paketa.
3. Instalirajte Twine: Pokrenite `pip install twine`.
4. Prenesite svoj paket: Pokrenite `twine upload dist/*`. Bit ćete upitani za korisničko ime (__token__) i lozinku (API token koji ste stvorili).

Važna sigurnosna napomena: Nikada nemojte pohranjivati svoj API token u svoj repozitorij. Pohranite ga na sigurno i koristite varijable okruženja ili druge sigurne metode za pristup tijekom procesa prijenosa.

Testiranje instalacije vašeg paketa

Nakon objavljivanja vašeg paketa, ključno je testirati može li se ispravno instalirati.

1. Stvorite novo virtualno okruženje: To osigurava da testirate instalaciju u čistom okruženju.
2. Instalirajte svoj paket: Pokrenite `pip install ime-vaseg-paketa`.
3. Uvezite i koristite svoj paket: U Python interpreteru uvezite svoj paket i provjerite radi li kako je očekivano.

Kontinuirana integracija i kontinuirana isporuka (CI/CD)

Za automatizaciju procesa izgradnje, testiranja i objavljivanja vašeg paketa, možete koristiti CI/CD alate kao što su GitHub Actions, GitLab CI ili Travis CI.

Evo primjera tijeka rada (workflow) za GitHub Actions koji gradi i objavljuje vaš paket na PyPI:

name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python 3.x
      uses: actions/setup-python@v2
      with:
        python-version: 3.x
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel twine
    - name: Build package
      run: python setup.py sdist bdist_wheel
    - name: Publish package to PyPI
      run: |
        twine upload dist/* \
          -u __token__ \
          -p ${{ secrets.PYPI_API_TOKEN }}

Objašnjenje:

• Ovaj tijek rada pokreće se kada se na GitHubu objavi novo izdanje.
• Provjerava kod, postavlja Python, instalira ovisnosti, gradi paket i prenosi ga na PyPI.
• secrets.PYPI_API_TOKEN je GitHub tajna (secret) koja pohranjuje vaš PyPI API token. Morate konfigurirati ovu tajnu u postavkama vašeg GitHub repozitorija.

Najbolje prakse za distribuciju Python paketa

• Napišite sveobuhvatnu dokumentaciju: Uključite detaljnu `README.md` datoteku, kao i API dokumentaciju koristeći alate poput Sphinxa. Jasna i potpuna dokumentacija ključna je kako bi vaš paket bio jednostavan za korištenje.
• Pišite jedinične testove: Temeljito testirajte svoj kod kako biste osigurali njegovu kvalitetu i pouzdanost. Koristite okvire za testiranje poput pyquesta ili unittesta.
• Slijedite smjernice stila PEP 8: Pridržavajte se vodiča za stil Python Enhancement Proposal 8 (PEP 8) kako biste osigurali dosljedan i čitljiv kod.
• Koristite licencu: Odaberite odgovarajuću licencu otvorenog koda kako biste specificirali kako drugi mogu koristiti vaš kod.
• Održavajte ovisnosti ažurnima: Redovito ažurirajte ovisnosti vašeg paketa kako biste iskoristili ispravke grešaka, sigurnosne zakrpe i nove značajke.
• Koristite virtualno okruženje: Uvijek razvijajte i testirajte svoj paket unutar virtualnog okruženja kako biste izolirali ovisnosti.
• Razmotrite internacionalizaciju (i18n) i lokalizaciju (l10n): Ako vaš paket obrađuje tekst ili podatke vidljive korisnicima, razmislite o prilagodbi različitim jezicima i regijama. To proširuje vašu potencijalnu bazu korisnika na globalnoj razini. Alati poput Babela mogu pomoći u tome.
• Rukujte različitim vremenskim zonama i valutama: Ako se vaš paket bavi datumima, vremenima ili financijskim transakcijama, budite svjesni različitih vremenskih zona i valuta diljem svijeta. Koristite odgovarajuće biblioteke i API-je za ispravno rukovanje tim složenostima.
• Pružite jasne poruke o greškama: Pišite informativne poruke o greškama koje pomažu korisnicima da shvate što je pošlo po zlu i kako to popraviti. Prevedite te poruke na različite jezike ako je moguće.
• Razmišljajte o pristupačnosti: Uzmite u obzir korisnike s invaliditetom pri dizajniranju sučelja i dokumentacije vašeg paketa. Slijedite smjernice za pristupačnost kako biste osigurali da je vaš paket upotrebljiv svima.

Napredne teme

• Namespace paketi: Omogućuju vam da podijelite jedan Python paket na više direktorija ili čak više distribucija.
• Ulazne točke (Entry points): Omogućuju vam definiranje funkcija ili klasa koje se mogu pozvati iz drugih paketa ili s naredbenog retka.
• Datoteke s podacima: Omogućuju vam uključivanje datoteka koje nisu Python kod (npr. datoteke s podacima, konfiguracijske datoteke) u vašu distribuciju.
• Uvjetne ovisnosti: Omogućuju vam da specificirate ovisnosti koje su potrebne samo pod određenim uvjetima (npr. na određenom operativnom sustavu).

Zaključak

Distribucija vašeg Python paketa na PyPI-ju sjajan je način da podijelite svoj rad sa svijetom i doprinesete Python ekosustavu. Slijedeći korake i najbolje prakse navedene u ovom vodiču, možete stvoriti i objaviti visokokvalitetne Python pakete koji su jednostavni za instalaciju, korištenje i održavanje. Ne zaboravite dati prioritet jasnoj dokumentaciji, temeljitom testiranju i dosljednom upravljanju verzijama kako biste osigurali uspjeh vašeg paketa.